<html>
<head>
<title>CartoDB</title>
</head>

<body bgcolor="#ffffff">

<h1>CartoDB</h1>

(GDAL/OGR &gt;= 1.11)<p>

This driver can connect to the services implementing the CartoDB API.
GDAL/OGR must be built with Curl support in order for the
CartoDB driver to be compiled.<p>

The driver supports read and write operations.<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a CartoDB datasource is : <pre>CartoDB:[connection_name]</pre><p>

For single-user accounts, connection name is the account name.
For multi-user accounts, connection_name must be the user name, not the account name.

Additionnal optional parameters can be specified after the ':' sign.
Currently the following one is supported :<p>

<ul>
<li> <b>tables=table_name1[,table_name2]*</b>: A list of table names.
This is necessary when you need to access to public tables for example.
</ul>

If several parameters are specified, they must be separated by a space.<p>

<h2>Configuration options</h2>

The following configuration options are available :
<ul>
<li>CARTODB_API_URL: defaults to https://[account_name].cartodb.com/api/v2/sql.
Can be used to point to another server.</li>
<li>CARTODB_HTTPS: can be set to NO to use http:// protocol instead of
https:// (only if CARTODB_API_URL is not defined).</li>
<li>CARTODB_API_KEY: see following paragraph.</li>
</ul>


<h2>Authentication</h2>

Most operations, in particular write operations, require an authenticated
access. The only exception is read-only access to public tables.<p>

Authenticated access is obtained by specifying the API key given in the
management interface of the CartoDB service. It is specified with the
CARTODB_API_KEY configuration option.<p>

<h2>Geometry</h2>

The OGR driver will report as many geometry fields as available in the
layer (except the 'the_geom_webmercator' field), following RFC 41.

<h2>Filtering</h2>

The driver will forward any spatial filter set with SetSpatialFilter() to
the server. It also makes the same for attribute
filters set with SetAttributeFilter().<p>

<h2>Paging</h2>

Features are retrieved from the server by chunks of 500 by default.
This number can be altered with the CARTODB_PAGE_SIZE
configuration option.<p>

<h2>Write support</h2>

Table creation and deletion is possible.<p>

Write support is only enabled when the datasource is opened in update mode.<p>

The mapping between the operations of the CartoDB service and the OGR concepts is the following :
<ul>
<li>OGRFeature::CreateFeature() &lt;==&gt; INSERT operation</li>
<li>OGRFeature::SetFeature() &lt;==&gt; UPDATE operation</li>
<li>OGRFeature::DeleteFeature() &lt;==&gt; DELETE operation</li>
<li>OGRDataSource::CreateLayer() &lt;==&gt; CREATE TABLE operation</li>
<li>OGRDataSource::DeleteLayer() &lt;==&gt; DROP TABLE operation</li>
</ul>

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the
returned rowid and use it as the OGR FID.<p>

The above operations are by default issued to the server synchronously with the OGR API call. This however
can cause performance penalties when issuing a lot of commands due to many client/server exchanges.<p>

So, on a newly created layer, the INSERT of CreateFeature() operations are grouped together
in chunks until they reach 15 MB (can be changed with the CARTODB_MAX_CHUNK_SIZE
configuration option, with a value in MB), at which point they are transferred
to the server. By setting CARTODB_MAX_CHUNK_SIZE to 0, immediate transfer occurs.<p>

<h2>SQL</h2>

SQL commands provided to the OGRDataSource::ExecuteSQL() call are executed on the server side, unless the OGRSQL
dialect is specified. You can use the full power of PostgreSQL + PostGIS SQL
capabilities.<p>

<h2>Open options</h2>

<p>Starting with GDAL 2.0, the following open options are available:</p>
<ul>
<li><b>BATCH_INSERT</b>=YES/NO: Whether to group feature insertions in a batch.
Defaults to YES. Only apply in creation or update mode.</li>
</ul>

<h2>Layer creation options</h2>

<p>The following layer creation options are available:</p>
<ul>
<li><b>OVERWRITE</b>=YES/NO: Whether to overwrite an existing table with the
layer name to be created. Defaults to NO.</li>

<li><b>GEOMETRY_NULLABLE</b>=YES/NO: Whether the values of the geometry column
can be NULL. Defaults to YES.</li>

<li><b>CARTODBFY</b>=YES/NO: Whether the created layer should be "CartoDBifi'ed"
 (i.e. registered in dashboard). Defaults to YES.</li>

<li> <b>LAUNDER</b>=YES/NO: This may be "YES" to force new fields created on this
layer to have their field names "laundered" into a form more compatible with
PostgreSQL.  This converts to lower case and converts some special characters
like "-" and "#" to "_".  If "NO" exact names are preserved.
The default value is "YES".  If enabled the table (layer) name will also be laundered.</li>

</ul>


<h2>Examples</h2>

<li>
Acceccing data from a public table:
<pre>
ogrinfo -ro "CartoDB:gdalautotest2 tables=tm_world_borders_simpl_0_3"
</pre>
<p>

<li>
Creating and populating a table from a shapefile:
<pre>
ogr2ogr --config CARTODB_API_KEY abcdefghijklmnopqrstuvw -f CartoDB "CartoDB:myaccount" myshapefile.shp
</pre>
<p>

<h2>See Also</h2>

<ul>
<li> <a href="http://docs.cartodb.com/cartodb-platform.html">CartoDB API overview</a><p>
</ul>

</body>
</html>
